Summary

The current tool descriptions for perplexity_ask, perplexity_research, and perplexity_reason are nearly identical ("Accepts an array of messages...and returns a response"), giving AI agents no basis for choosing between them. This PR rewrites descriptions and adds supporting metadata to make tool selection intuitive for agents.

Changes

• Server-level instructions: Added an instructions field to the McpServer constructor, giving agents a high-level overview of all tools and when to use each one. This is surfaced in the MCP initialize response.

• Rewritten tool descriptions: All 4 tool descriptions now follow an action-first format with:

  • What the tool does and which model it uses
  • "Best for:" guidance listing concrete use cases
  • Return shape description
  • Cross-references to alternative tools ("For X, use Y instead")

• Constrained role parameter: Changed role from z.string() to z.enum(["system", "user", "assistant"]) so agents see the valid values in the schema rather than guessing.

• Improved output schema descriptions: Made return shapes explicit (e.g., "AI-generated text response with numbered citation references" instead of "The response from Perplexity").

• Added idempotentHint: true to all tool annotations: All 4 tools are read-only queries that can be safely retried without side effects.

Why

When an agent receives a list of MCP tools, descriptions are the primary signal for tool selection. The previous descriptions were generic and duplicated across tools, forcing agents to guess or pick arbitrarily. These changes give agents clear disambiguation criteria, reducing misrouted calls and improving response quality — especially in multi-tool workflows where the agent needs to decide between a quick answer (perplexity_ask), deep research (perplexity_research), or step-by-step reasoning (perplexity_reason).

Test plan

• npm run build — TypeScript compiles cleanly
• Verify all 4 tools listed with new descriptions via MCP inspector
• Verify role parameter shows enum constraint in schema
• Verify idempotentHint appears in tool annotations
• Verify server instructions appear in initialize response

🤖 Generated with Claude Code